home *** CD-ROM | disk | FTP | other *** search
/ Workbench Design / WB Collection.iso / workbench werkzeuge / memory & system tools / stackmon / stackmon.doc < prev    next >
Text File  |  1996-04-07  |  4KB  |  120 lines
  1.  
  2.                    StackMon v1.3
  3.                    -------------
  4.  
  5.                © 1993-94 David Kinder
  6.                ----------------------
  7.  
  8. Introduction
  9. ------------
  10.  
  11. StackMon is a small utility to help programmers (and other users). Amiga
  12. programs use their stack (a special area of memory) to store temporary
  13. addresses, data, etc. The default stack is 4096 bytes, but this may not
  14. be enough; some compilers can require over 100Kb. The stack size for a shell
  15. is set by the 'stack' command. For a program run from Workbench, the size
  16. is given in the icon; use the Workbench 'Information' option to examine
  17. this value.
  18.  
  19. Use
  20. ---
  21.  
  22. StackMon requires AmigaDOS 2.04 or higher. There are no startup options;
  23. just run StackMon from a shell or click on its icon.
  24.  
  25. When run StackMon presents a list of all the tasks and processes currently
  26. running. The list is sorted alphabetically, with processes before tasks.
  27. This list is not updated automatically, as constructing this list requires
  28. suspension of multitasking. If you run a program you want to monitor after
  29. starting StackMon, click on the 'Update list' gadget so that it appears in
  30. the list.
  31.  
  32. If the program you want to monitor was run from the Workbench, its name will
  33. be that of the icon; if run from the shell the name is the exact name typed
  34. into the shell, with path.
  35.  
  36. Click on the program you wish to monitor and StackMon will begin monitoring.
  37. The display consists of numbers and a fuel gauge showing the current stack
  38. use relative to the size of the stack. The numbers are:
  39.  
  40. Current: This is the amount of stack in use when the program was last
  41.      monitored.
  42. Largest: The largest recorded stack ever in use by this program.
  43. Stack  : The stack allocated for this program.
  44.  
  45. You can also tell StackMon which program to monitor by entering its name
  46. in the string gadget below the task list. The name entered must be
  47. EXACTLY that of the program, i.e. if the program is to be started with
  48.  
  49.     1> work:drawer/program
  50.  
  51. You must type 'work:drawer/program' into the gadget, making sure that
  52. the case of all characters matches. If the program is not found, StackMon
  53. will periodically search the task list for the program. If the program
  54. appears, monitoring will begin. In this way StackMon can be used to
  55. monitor programs that only run for a short time before exiting.
  56.  
  57. If the program terminates while being monitored, monitoring ceases, and the
  58. message 'Task not found' appears in the window. Monitoring of a program
  59. can also be stopped by clicking on the 'Stop' gadget. To change from
  60. monitoring one program to another, simply click on the other program's name
  61. in the list.
  62.  
  63. If the program exceeds its allowed stack, the message 'Stack Overflow'
  64. will appear. Note that this behaviour by a program will make the system
  65. very unstable and a crash is probably imminent. When setting the stack for
  66. a program, always leave at least ~2Kb extra space, since DOS can also
  67. use this stack and future versions of DOS may use more stack.
  68.  
  69. Caveat
  70. ------
  71.  
  72. StackMon takes a 'snapshot' of the stack use of a program, so a very sudden
  73. 'burst' of stack use may be missed. This is not very likely, however, as
  74. StackMon checks the program several times a second.
  75.  
  76. Compiler
  77. --------
  78.  
  79. StackMon was written using Amiga E v2.1b, a freely distributable compiler.
  80. Note that E programs have their own stack managememt system, so StackMon is
  81. not useful with these programs. However, E programs do not appear to ever
  82. have stack overflow problems, as the compiler estimates the stack required
  83. at compile time.
  84.  
  85. History
  86. -------
  87.  
  88. v1.0    First release.
  89.  
  90. v1.1    Renamed 'Cancel' gadget to 'Stop'.
  91.     Task list is now sorted alphabetically.
  92.     Added string gadget to allow user to type in name of program
  93.     to be monitored.
  94.     Removed Enforcer hits. (Thanks to Karsten Weiss for Enforcer
  95.     testing and suggesting some improvements.)
  96.  
  97. v1.2    String gadget is always active.
  98.     StackMon now continually checks the maximum stack size so that
  99.     stack swapping (as performed eg. by the shell) is monitored
  100.     correctly.
  101.     Routine to find task name improved.
  102.     Impossible stack sizes (eg. negative) are replaced by '???'.
  103.  
  104. v1.3    Handles being opened on a public screen.
  105.     List gadget is now the correct size under AmigaDOS 3.1.
  106.  
  107. Address
  108. -------
  109.  
  110. Bug reports, comments, etc. to:
  111.  
  112. Internet email (prefered): kinder@teaching.physics.ox.ac.uk
  113.                dkinder@vax.ox.ax.uk
  114.  
  115. Post: David Kinder,
  116.       2, Clwtt Cottages,
  117.       Bangor Rd.,
  118.       Gyfelia,
  119.       Clwyd. LL13 0YL.
  120.